APPLESOFT ACADEMY
By Chris Birch
Copyright (c) 1991 Apple Users' Group, Sydney
Republished from Applecations, a publication of the Apple Users' Group, Sydney, Australia.


THIS MONTH: High resolution colour graphics

The first in a series exploring Applesoft - the native programming language of the Apple II family of computers. If you own or use an Apple II or compatible computer (including the Apple III or Mac LC with emulation or Laser, Redstone, etc.) then read on.
The hardware requirements are a 40 column original, compatible or emulated Apple II family computer with 48K of RAM and a colour screen (television or monitor), DOS 3.3 and Applesoft.
An intermediate knowledge of Applesoft is all that is required. You should be able to type in, edit, LIST, RUN and SAVE an Applesoft program. Ideally, you want to graduate from your "Applesoft Tutorial" or "Touch of" manual and what better place to do this than from the Applesoft Academy!

Turning on the graphics
This month we'll investigate the built in high resolution graphics of your Apple II family computer. There are several "high res" graphics functions built in to Applesoft and the best place to start is with the two commands that enable all the other high res functions.

HGR Command
As you will already know from your Applesoft manual (for owners of early model Apples I assume this to be the "Tutorial" manual) this is the command that switches the top 20 text lines of the screen from displaying text to high res graphics. The last 4 text lines are still able to show text.
You can of course issue the text PRINT commands and the high res HPLOT commands at any time but they will only appear on the screen if you have enabled the correct display mode.
If you HPLOT while the full text screen is turned on then you will not see your results. If you then do a HGR to turn the high res graphics on then you will still not see the effect of your HPLOT. The reason for this is that Applesoft clears the high res graphics screen to black each time the command is invoked. Because of this clearing effect you must use HGR as the first command in a sequence of high resolution graphics commands.
(Advanced: It is possible to avoid this clearing effect)

HGR2 Command
This command has a similar effect as above except that no space is reserved for text at the bottom of the screen. This means that there is more space for plotting on the screen.

Using the HGR and HGR2 commands
When in HGR mode you can plot 280 points across and 160 points down the screen. In HGR2 mode you can plot 280 points
across and 192 points down. The maximum number of points able to be plotted horizontally and vertically on the screen is known as the "resolution" of the computer's graphics.
After invoking HGR or HGR2 mode a simple TEXT command restores the screen to text mode. You will notice that text typed on the screen before invoking HGR or HGR2 is still there after you issue a TEXT. This is because a different part of memory is used to display TEXT, HGR and HGR2. The Applesoft commands allow you to switch to the different parts of memory and then change the memory locations, which then appear on the screen. Such a set of memory locations is known as a "screen page". Note that when in HGR mode you are actually displaying the HGR page and the last four lines of the TEXT page at once!
(Advanced: To plot graphics or print text as fast as possible you place the information directly into computer memory instead of letting Applesoft do it for you.)

Now what?
Let's now explore ways of plotting points on the screen. The same principle as plotting points on graph paper are involved. You may have guessed this already.

HPLOT command
This is the command used to place output on the screen. The screen is like a sheet of graph paper with each line on the grid assigned a number. The vertical lines are numbered from 0 to 279 moving left to right across the screen. The horizontal lines are numbered 0 to 159 as you move down the screen. This assumes you are using the HGR graphics mode. The HGR2 graphics mode goes from 0 to 191 because it uses all the screen. The HGR mode displays four lines of TEXT  at the bottom of the screen instead.
This means the top left hand corner is location 0,0 and the bottom right hand corner is 279,159 or 279,191. This may not be the same convention you are used to when plotting points on graph paper.
There are several ways to use the HPLOT command:

(a) HPLOT 100,80
Plot the one hundred and first point across and eighty first point down.
(b) HPLOT 9,19 TO 269,139
Plot a line from 9,19 to 269,139.
(c) HPLOT TO 235,50
Plot a line from the last point plotted on the screen to 235,50.

Let's do that now!

Example 1
10  HGR
20  HCOLOR = 3
30  HPLOT 100,80
40  HPLOT 9,19 TO 269,139
50  HPLOT TO 235,50

Type TEXT and hit RETURN to restore to full text mode. The Applesoft in an Apple IIgs is mostly the same as the built in Applesoft of an original Apple II with an Applesoft card. One important difference is that an Apple IIgs will not automatically set the colour of the screen to white. It leaves it as black. That is why the example above sets the initial high res colour (to white).
We're now ready to introduce some colour to our programming.

HCOLOR command
You can specify the colour in which the plotted points are to appear. The following colours are available:

0    Black 1
1    Green
2    Magenta (Violet)
3    White 1
4    Black 2
5    Orange
6    Cyan (light blue)
7    White 2

The next example illustrates the four different colours available, excluding white and black. Note that we are forced to spell "colour" the American way whenever we program in Applesoft:

Example 2
10  HGR
20  HCOLOR = 1 : HPLOT 5,10 TO 5,100
30  HCOLOR = 2 : HPLOT 36,10 TO 36,100
40  HCOLOR = 5 : HPLOT 65,10 TO 65,100
50  HCOLOR = 6 : HPLOT 96,10 TO 96,100

(Advanced: Notice how the text continues to scroll up the text screen. It is possible to limit the scrolling of text to the bottom four lines of the screen)
Example 2 was deliberately contrived so that it would work. Try replacing the x-coordinates (i.e. the horizontal points) with an odd number for an even number or vice-versa. Nothing will appear on the screen! This is because GREEN and ORANGE can only be plotted with ODD coordinates and VIOLET and BLUE can only be plotted with EVEN coordinates. The vertical position doesn't matter.
So, when plotting a purely horizontal line you will get a solid line, but it only appears to be solid as every second point is actually black. Try plotting the diagonal lines in example 3 and the gaps will be noticeable.

Example 3
10  HGR
20  HCOLOR = 1 : HPLOT 5,10 TO 25,100
30  HCOLOR = 2 : HPLOT 36,10 TO 56,100
40  HCOLOR = 5 : HPLOT 65,10 TO 85,100
50  HCOLOR = 6 : HPLOT 96,10 TO 116,100

It is possible to take advantage of these limitations but first let's try example 4:

Example 4
10  HGR
20  HCOLOR = 6
30  FOR X = 0 TO 279
40  FOR Y = 0 TO 159
50  HPLOT X,Y
60  NEXT : NEXT

Slow eh? Change line 30 as follows so as to double the speed:

30  FOR X = 0 TO 278 STEP 2

You are taking advantage of the fact that BLUE can only be plotted on EVEN x coordinates, so why bother plotting on the odd coordinates? Note that 0 is EVEN and also that even though you have only plotted every second line, the colour appears solid.
(Advanced: Notice how the 3rd and 10th Orange segment and the 5th Cyan segment were darker than the other segments in Example 3)

Whiter than white?
You will recall the problem of "blacking out" in example 3. This only ever happens when the line to be plotted is not purely horizontal or vertical. This can be avoided by selecting either of the WHITE colours when plotting a diagonal line. Try example 5. It's the same as example 3 except the colours have been changed to WHITE.

Example 5
10  HGR
20  HCOLOR = 3 : HPLOT 5,10 TO 25,100
30  HCOLOR = 3 : HPLOT 36,10 TO 56,100
40  HCOLOR = 7 : HPLOT 65,10 TO 85,100
50  HCOLOR = 7 : HPLOT 96,10 TO 116,100

You will note that the result is far from being white. Choosing WHITE 1 will allow Applesoft to plot either a GREEN or VIOLET point depending upon whether the x-coordinate is ODD or EVEN respectively. What Applesoft does with WHITE 2 is left to you as an exercise.
The white spots appearing along each line may be a bit of a surprise though. This is because when adjacent odd and even points are lit the two points appear as white. This is
another important rule to note. It is the only way to generate a true white colour on the screen.

Wrong colours
The following example will produce a surprising result. We would expect a GREEN horizontal line with an ORANGE vertical line bisecting it and a WHITE dot in the middle where the two lines intersect (remember - adjacent points produce a thick WHITE point):

Example 6
10  HGR
20  HCOLOR = 1 : HPLOT 50,100 TO 100,100
30  HCOLOR = 5 : HPLOT 75,50 TO 75,150

Part of the GREEN line has changed to ORANGE because of the peculiar way the computer uses its memory. Now change line 30 to line 20 and vice-versa and note that the problem doesn't exist anymore. Change the lines back again and then this time substitute BLUE for ORANGE. Don't forget to adjust the x-coordinate to an even number. At last! Part of the GREEN line is ORANGE. An explanation is in order.

Byte sized pieces
Each horizontal line occupies 40 small chunks of memory known as "bytes". Seven points across the screen belong to each byte. A byte could actually hold eight points but one of the eight "bits" is used to indicate the colour of the seven points. If the colour bit has a value of 1 (it can only equal 1 or 0) then the seven points belonging to the byte will use the BLUE, ORANGE, BLACK 2 and WHITE 2 colours. When the bit is 0 then the other colours are valid.
From our previous examples we can also correctly deduce that all seven points cannot use the same colour. For instance, when the colour bit is a 0 then all seven points at the memory location cannot equal VIOLET. The odd points will be GREEN and the EVEN points VIOLET.
Recall example 6 where you plotted a GREEN horizontal line. Applesoft made the colour bit of the relevant memory locations a 0. Trying to bisect the GREEN line with an ORANGE or BLUE vertical line produced disastrous results because Applesoft had to make the colour bit a 1 at the point of intersection. But this is a memory location shared by two lines with opposite colour requirements.
The reason why part of the GREEN line changed colour is simple. Applesoft decided to use the colours that were LAST requested at that memory location. To avoid these problems the solution is to plot the vertical lines first and the horizontal lines last! I'll leave this as an exercise for you to further refine the previous example.

Snow storm
Whew! A lot of ground was covered in this tutorial. Experienced programers will recognise that I've glossed over
the discussion of "bits", "bytes" and memory locations. Beginners will now know that you don't need to know all about bits, bytes and memory in order to do graphics programming.
All levels of programmer will hopefully have gained some insight into how to control the colours on the screen. To show how to make the graphics screen go totally out of control just type in the following program, sit back and enjoy.

Example 7
10  HGR
20  HCOLOR = 7
30  X=INT(RND(2) * 279 + 0.5)
40  Y=INT(RND(2) * 159 + 0.5)
50  HPLOT X,Y
60  GOTO 20

Oh, the only way to stop the program is to simultaneously press CONTROL and C. Try experimenting with line 20. You may find the program works better with a black and white screen.

Next time
The last fun example, above, used the built in random number generator (i.e. the RND command) in Applesoft. The next Applesoft Academy will explore the RND command further and put to use our new high resolution graphics skills. Until then, here's a thought to consider:
(Advanced: A close inspection of the screen after some of the examples have been run reveals further apparent anomalies in screen colours. This is easily explained away as "hardware timing problems" but it is very difficult to describe. The best explanation to date is found in "Understanding the Apple II", 1983 by James Sather, Quality Software, CA. ISBN 0-912985-01-1)

THIS CONTENT COPYRIGHT © 2007, APPLE MACINTOSH USERS' GROUP, SYDNEY
Permission has been obtained to make this material available on the Internet.

Permission is hereby granted for non-profit user groups to republish this content.
PLEASE CREDIT THE AUTHOR AND THE SOURCE: Applecations, publication of the Apple Users' Group, Sydney, Australia

THIS PAGE COPYRIGHT © 2007, ANDREW ROUGHAN